classdef dotsPlayable < dotsAllManagedObjects
    % @class dotsPlayable
    % Superclass for playable sound objects
    
    properties (SetObservable = true)
        
        % true or false, whether to play() this object.
        isAudible;

        % scale factor to apply to waveform during playback.
        intensity = 1;
        
        % frequency in Hz of sound samples stored in waveform.
        sampleFrequency;

        % bit-depth of each sound sample in waveform.
        bitsPerSample;
    end
    
    properties (SetObservable = false)
        
        % mxn double matrix of sound samples (arbitrary units, 0-1)
        %   - m is the number of channels, 1 for mono and 2 for stereo
        %   - n is the number of sound samples (the length of the sound)
        waveform;
        
        % system path to locate sound files.
        % Use dotsTheMachineConfiguration to specify a machine-specific
        % soundsPath.
        soundsPath;
    end
    
    methods
        function self = dotsPlayable
            self = self@dotsAllManagedObjects;
            
            % set machine-specific and other defaults
            dotsTheMachineConfiguration.applySettingsToObject(self);
            dotsTheMachineConfiguration.applySettingsToObjectAsClass( ...
                self, 'dotsPlayable');
            
            self.isAudible = true;
            dotsTheSwitchboard.sharePropertyOfObject('isAudible', self);
        end
        
        % play() or not, depending on isAudible and possibly other factors
        function mayPlayNow(self)
            if self.isAudible
                self.play;
            end
        end
        
        % do any pre-play setup
        function prepareToPlay(self)
        end
        
        % subclass must redefine play()
        function play(self)
        end
        
        % shorthand for isAudible=true
        function unMute(self)
            self.isAudible = true;
        end
        
        % shorthand for isAudible=false
        function mute(self)
            self.isAudible = false;
        end
    end
end